﻿<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="8" MadCap:lastHeight="728" MadCap:lastWidth="918">
    <head><title>MxPlugin Rules</title>
    </head>
    <body>
        <h1>MxPlugin Rules</h1>
        <p>The rules for using MxPlugin objects are much the same as when you use COM objects as explained in Essential COM (Don Box, 1998, Addison Wesley:</p>
        <ol>
            <li>Once an interface is published, it must never be changed. That is to say IPluginStdInterface.h can never be changed once it has been put into the Public Interfaces folder. If you need  to make changes then just create a new interface - i.e. Sample2I.h</li>
            <li>Interfaces must:<ol><li>only contain pure virtual functions with MXSTDMETHOD to define the calling convention<ul><li>•	<code>virtual long  MXSTDMETHOD DestroyPtr(void) = 0;</code></li></ul></li><li>the input parameters and return values of these virtual functions must be:<ol><li>PODs (plain old datatypes, like int, long, char *)</li><li>Other interfaces (ISample)</li><li>Any Enumerations must contain a long (i.e. pad = 0xEFFFFFFF) so they cannot be optimised by the compiler to a shorter datatype (such optimisation depends on the compiler / vendor).</li></ol></li></ol></li>
            <li>Interfaces can inherit from only one interface. Multiple inheritance is not allowed as the binary representation of the resulting C++ abstract class depends on the compiler / vendor. - see Essential COM (Don Box, 1998, Addison Wesley), 1st ed, 2nd printing, p52</li>
            <li>All interfaces must inherit directly or indirectly from IMxPluginBase.<ul><li>Therefore, the following would be ok:<ul><li>class ISample : public IMxPluginBase</li><li>class ISample2 : public ISample</li><li>class ISample3 : public ISample2</li></ul></li></ul><ul><li>The following are NOT ok:<ul><li>class ISample	//BAD: does not inherit from IMxPluginBase</li><li>class ISample : public IMxPluginBase, ISample2	//BAD: multiple inheritance</li></ul></li></ul></li>
            <li>Call DuplicatePtr() when copying an interface pointer - see Essential COM (Don Box, 1998, Addison Wesley), 1st ed, 2nd printing, p54</li>
            <li>Call DestroyPtr() when an interface pointer is no longer needed - see Essential COM (Don Box, 1998, Addison Wesley), 1st ed, 2nd printing, p54</li>
            <li>Do not overload methods defined in the interface - i.e. same member function name, but different argument list</li>
            <li>Exceptions cannot be passed between MxPlugin libraries and their consumers.</li>
            <li>Any given DLL may contain the implementation of multiple interfaces, but it cannot have multiple implementations of the same interface. That is to say PluginStdInterfaceLib.dll may implement the interfaces ISample and IMxPluginBase, but when its CreateClassInstance() is passed the IId of ISample ("0ED26723-EB8F-44B7-B45E-7475BDE1E706") it will always create and return an object of class Sample in order to provide its implementation of ISample. Clearly,	it would make no sense to have another class in PluginStdInterfaceLib.dll like SampleXYZ that also implemented the interface ISample.</li>
        </ol>
    </body>
</html>